home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1997 August / Macworld (1997-08).dmg / Shareware World / Info / For Developers / InstallerMaker™ 4.0 Installer / Customizing InstallerMaker / Sample Code / Documentation / About IM Location Extns next >
Text File  |  1997-05-12  |  5KB  |  112 lines
  1. About IM Locations Extensions
  2. ____________________________________________
  3.  
  4. By Raymond Lau
  5. 95.01.21
  6.  
  7. Revised by Rob Thorne (RMT) 95.08.03
  8.  
  9. A technical memorandum.
  10.  
  11. Copyright © 1994-97, Aladdin Systems, Inc.  All Rights Reserved.
  12.  
  13. ____________________________________________
  14.  
  15. Location extensions serve two purposes:
  16.  
  17. 1. They allow setting up custom locations, such as a special folder in the Preferences folder.
  18.    
  19. 2. They allow customization of where the user specified folder/volume defaults to and can further force the USF/USV.  For example, a SITcomm update installer may have an extension which first searches for SITcomm and if found, automatically installs in that folder, else, the installer will put up a SFPutFile.
  20.  
  21. These two uses are somewhat overlapping but also somewhat distinct.  Any given extension may handle either or both.
  22.  
  23. Location extensions are internally identified by rsrc ID.  Currently, these IDs must be negative.  Because identification is by IDs, Aladdin will devise guidelines for assigning IDs and ranges.  We recommend  registering your resource ID if you expect you will distribute your location module to other developers (as we encourage you to do!).
  24.  
  25. The id range of -5000 to -5999 is reserved for Aladdin Systems, Inc.; please don't use this range for your modules.
  26.  
  27. What Needs To Be In A Location Module?
  28. ____________________________________________
  29.  
  30. Each location extension should be in a separate file, which we will call
  31. a "location module".  The location module must contain the following 
  32. resources:
  33.  
  34. 'STR ' -32767 - The name of the location to be displayed in the menu.
  35.  
  36. 'Flag' -32767 - An unsigned short.  Bits are as follows:
  37.                     0 - This can function as a custom location atom.
  38.                     1 - This can function as a USF/USV direction atom.
  39. 'vers' (-32767 or ILoc ID)
  40.  
  41. icon family (same ID as ILoc; these get displayed in InstallerMaker menus)
  42.  
  43. 'ILoc' <appropriate negative id> - The atom code for the location extension.
  44.  
  45. The module may also contain other resources such as ALRTs, DLOGs or PICTs that your module needs to use during installation. These resources will be copied from your module into your product installer at build time.  You are responsible for checking the resource id's that you use against the Installer Resources file (Beta Testers: this may still be called "English To Localize" in your release.) to assure that your resource id's don't  conflict with ones that we use.
  46.  
  47. The file type must be 'Loca' and the creator must be 'STin.'
  48.  
  49. Locations extensions goes into a folder named "Locations" in the same folder as IM.
  50.  
  51. Note -- The IMEnvironsRec is documented in the IM 3.0 Code Spec documentation.
  52.  
  53. The 'ILoc' code rsrc has the following 68k calling convention:
  54.  
  55.     pascal short ILoc(IMEnvironsRec *environs,
  56.                     short *locVol,long *locDir,
  57.                     short *killDestinationPrompt,
  58.                     unsigned long *refcon);
  59.  
  60. In the custom location mode:
  61.  
  62.     userVol/userDir will be the USF or USV if known, or zero otherwise.
  63.                     (It may be zero when called during package selection before
  64.                     the actual userVol/userDir are known.)
  65.  
  66.     userSysVol/userSysDir will be the destination volume for system items.
  67.                     This is usually the active system folder but it may be changed
  68.                     by the user if that option is allowed by the developer.
  69.  
  70.     packages will be whatever the current package settings are. If 
  71.      the user has not yet selected the packages, the standard 
  72.      package is what is set by default.
  73.  
  74.     refcon will be the standard SEA atom refcon field used for other 
  75.      SEA atoms.
  76.  
  77.     The atom should return a valid *locVol/*locDir which is where items with the location which goes with this atom will be installed/located.
  78.     
  79.     The atom should also return an appropriate error code:
  80.  
  81.     0-no error (and locVol, locDir are valid)
  82.     1-an error occurred; skip this item
  83.     2-an error occurred; abort installation.
  84.  
  85.  
  86. In the direct USF/USV mode:
  87.  
  88.      userVol/userDir will be zero.
  89.  
  90.     userSysVol/userSysDir will be the destination volume for system items 
  91.        if available. This is usually the active system folder 
  92.        but it may be changed by the user if that option is allowed 
  93.        by the developer.
  94.  
  95.     refcon will be the standard SEA atom refcon field used for other 
  96.        SEA atoms.
  97.  
  98.     Initially, *locVol/*locDir will point to where we would normally direct
  99.     USF/USV without the location extension.
  100.     
  101.     The atom should return a valid *locVol/*locDir which is where the standard file dialog in the USF case and the select destination volume dialog in the USV case will be directed initially.
  102.     
  103.     If the atom sets *killDestinationPrompt to a non-zero value, then the SEA will not prompt the user for a USF/USV.  It will just use the one returned in *locVol/*locDir directly.  Note that in the USV case, it will not honor the actual *locDir and will just use the root level of *destVol.  The reason for this is in case some items are destined for USF and others are destined for USV, we want to maintain the two destinations as being distinct.
  104.  
  105.     The atom should also return an appropriate error code:
  106.  
  107.     0 - no error (and locVol, locDir are valid)
  108.     1 - an error occurred; point dialog to default locations (typically{-1, 2L})
  109.     2- abort installation
  110.  
  111.  
  112.